This is a brief note on what I know about apple events from hypercard 2.1. Take with chunk of salt. This is just stuff I found while I worked; not official stuff from Apple!!! I must thank John Calhoun, who is from apple, for all his help. If you have a hypercard/apple event question, just post it to MACPROG or info-mac; he is usually watching. Besides, lots of others with experience are watching too ;-).
The Hypertalk "send" command is meant to send script-like commands to other programs. Right now, only Hypercard (as far as I know) will eat this type of apple event.
If you want to send other kinds of apple events (like the core class of open app, close app, open docs, print docs) you must construct the apple event in an XCMD or XFCN.
One of the first things you need when getting an apple event together is a target address; the address of the program you are going to send to. Hypercard 2.1 provides the "answer program" hypertalk command to get this from the user (sort of a network version of the standard file dialog). Unfortunately, it returns an text-form address which is great for us humans, but bad for the rest of System 7.
Hypercard, however, comes to the rescue by providing a number of application defined coercion handlers (check out IM V, 6-100) that will change the text into a targetID record or a process serial number (see below).
If you need to save file descriptors in your apple events (as one would for the open doc and print doc events) you must get from the full path name of a file (that hypercard returns with its hypertalk answer file command) to a file spec or an alias record. The event record says we should use alias records. I found the simplest way to do with was to use the FSMakeFSSpec to create an FSSpec record (file system specification record) and then NewAlias to turn it into an alias record, and finally, use the apple event manager routines to stick the alias record into the apple event. But HEY watch it, the alias record is a variable length thing (I got bitten; took me several days to see my way around that error).
Other small hints: If you dest. program can't seem to decode the apple event properly, then suspect the sender. It is quite possible to assemble a corrupt apple event (I did that more times that I care to remember). Best way is to start by looking at some one else's code (there should be a number of XFCNs along with this note).
Another quick note on coercion handlers. The built in ones don't return addresses to GetCoearcionHandler -- so it looks like they aren't installed. For example, one way to see if you can convert a short int into a boolean with the apple event manager might be to try and get the coercion handler for "shor" to "bool". But, you will get an error (coercion handler not found). However, apple event manager will coerce from short to bool! That is what I call consistency.
Note that 'ADDR' isn't really a type. It takes, as input, a destination program (as returned by the hypertalk command answer program) and converts it to a typeProcessSerialNumber (if the prog is running on the local machine) or typeTargetID (if the prog is running on another machine).
